RISCOS Library
The
riscos library provides values
version, sys, dim, !, ?, $, dir, filetype, block
The number
version has the value 100 times
the RiscLua version number, for versions
higher than 5.00, and nil otherwise.
The function
sys behaves much like SYS in Basic.
It provides the means for RiscLua to call SWIs {
SoftWare Interrupts).
out0, out1, ... = sys (swi, in0, in1, ...)
The first argument is the SWI number or name. The subsequent arguments
are the register values on entry. A nil value indicates that the
register value on exit from the previous SWI call should be used. If
a string value is passed then the string is stored in a temporary
array whose address is used for the argument of the SWI.
The return values are the register values on exit from the SWI,
if the call succeeded without error. In case of error, the returned
values are nil followed by an error message.
RISC OS uses arrays to pass data in and out of SWIs if there are
more data than registers. The function
dim takes a number (giving how many bytes) or a string as argument and it allocates a garbage-collectible array in memory.
It returns the address of the start of the array, which is always a
multiple of 4. When the argument is a string enough bytes are
reserved to store the string, and the string is stored in the array
with no terminating zero byte. At the same time, as a
side-effect, it creates a userdatum
block[x] where
x is the address returned. The expression
#block[x] evaluates to the number of bytes
allocated at
x, which is convenient for checking
bounds. The array will not be garbage-collected while
block[x] is non-nil.
The riscos library provides three rather strange tables:
!, ? and
$. These
can be used like the indirection operators of Basic.
The values of these tables at a numeric index
(which must be a multiple of 4 for
!) give
the word, byte or zero-terminated string at that address in
memory. They can be assigned to as well as read. So what
in Basic might be:
DIM x% 15
?x% = 0
x%!4 = 15
$(x%+8) = "abc"
......
could be written in RiscLua as:
local !,?,$,dim in riscos
local x = dim(16)
?[x] = 0
![x+4] = 15
$[x+8] = "abc"
..........
Note that the argument of
dim determines the total
number of bytes, whereas in Basic the number is the highest offset,
i.e. one less.
The expression
$[b] gives the zero-terminated
string at address
b. The expression
$(b) gives the control-character-terminated
string at address
b, and
$(b,n) the string of length
n at address
b. However, the assignment
$[b] = s
stores the string
s at
b whatever control characters
s contains.
The directory iterator
dir used with the syntax:
for leafname, ftype in dir (dirname) do
................
end
The function
filetype takes the pathname
of a filer object as argument and returns nil if the object does not
exist and the numeric value of its filetype if it does.
It is up to the programmer to ensure that his or her code is safe.
In some ways, providing these more Basic-like facilities rather goes
against the security-conscious grain of Lua.